@honeybadger-io/js

Honeybadger for JavaScript

Universal JavaScript library for integrating apps with the :zap: Honeybadger Error Notifier.

❗Note: The NPM package has been moved to @honeybadger-io/js starting with v3.0.0. See the v2-stable branch for the honeybadger-js 2.x package. Upgrade instructions

Documentation and Support

For comprehensive documentation and support, check out our documentation site.

Changelog

See https://github.com/honeybadger-io/honeybadger-js/blob/master/CHANGELOG.md

Contributing

• Fork it.
• Create a topic branch git checkout -b my_branch
• Commit your changes git commit -am "Boom"
• Push to your branch git push origin my_branch
• Send a pull request

Development

• Run npm install.
• To run unit tests for both browser and server builds: npm test. Or separately: npm run test:browser, npm run test:server.
• To run integration tests across all supported platforms, set up a BrowserStack account and use BROWSERSTACK_USERNAME=your_username BROWSERSTACK_ACCESS_KEY=your-access-key npm run test:integration.
• To test the TypeScript type definitions: npm run tsd.

Bundling and types

This project is isomorphic, meaning it's a single library which contains both browser and server builds. It's written in TypeScript, and transpiled and bundled with Rollup. Our Rollup config generates three main files:

• The server build, which transpiles src/server.ts and its dependencies into dist/server/honeybadger.js.
• The browser build, which transpiles src/browser.ts and its dependencies into dist/browser/honeybadger.js.
• The minified browser build, which transpiles src/browser.ts and its dependencies into dist/browser/honeybadger.min.js (+ source maps).

In addition, the TypeScript type declaration for each build is generated into its types/ directory (ie dist/browser/types/browser.d.ts and dist/server/types/server.d.ts).

However, since the package is isomorphic, TypeScript users will likely be writing import * as Honeybadger from '@honeybadger-io/js' or import Honeybadger = require('@honeybadger-io/js') in their IDE. Our package.json has main and browser fields that determine which build they get, but there can only be a single type declaration file. So we use an extra file in the project root, honeybadger.d.ts, that combines the types from both builds.

Releasing

Releasing is done with two commands: npm version and npm publish. Both commands should be used with care. The npm publish command publishes to NPM and to our js.honeybadger.io CDN (hosted on AWS via S3/CloudFront).

For the CDN release, make sure you have the following environment variable available in your shell:

export HONEYBADGER_JS_S3_BUCKET=honeybadger-js
export HONEYBADGER_DISTRIBUTION_ID=cloudfront-id

AWS credentials are read from ~/.aws/credentials, using the default profile.

To perform a full release:

• With a clean working tree, use npm version [new version] to bump the version, commit the changes, tag the release, and push to GitHub. See npm help version for documentation.

• To publish the release, use npm publish. See npm help publish for documentation.

If the CDN release fails for some reason (bad AWS credentials, for instance), re-run the release manually with npm run release-cdn.

Release Automation

We use Ship.js to automate releasing. Our custom Ship.js config determines the next release version based on the unreleased section of our changelog (Keep a Changelog format).

Ship.js creates a PR once per week when unreleased changes are present. You can also trigger a release PR by saying "@shipjs prepare" in any issue or pull request comment on GitHub.

Available Commands

• npm run release - Calculates the next version and creates a PR via shipjs prepare. This can run locally or in CI
• npx shipjs trigger - Publish to NPM (usually happens in CI, but can also run locally)

GitHub Workflows

• shipjs-manual-prepare
• shipjs-schedule-prepare
• shipjs-trigger

Related Links

• Our Ship.js config file
• Our Changelog file
• Ship.js on GitHub
• Ship.js docs
• More about our unique setup

License

The Honeybadger gem is MIT licensed. See the MIT-LICENSE file in this repository for details.

We use BrowserStack to run our automated integration tests on multiple platforms in CI.